Paper Trading

This is an important tutorial for people wanting to use stockseyes API for paper trading.

In this tutorial, we will be doing the following steps to help you understand the API fully.

Token Generation
- Generate a token for the user using the API Key.
Search Instruments
- Search for Instruments we are interested in.
Get Current Quote
- Get the current quote for instruments of our interest.
Wallet
- Get wallet balance. It has a default balance of 0.
- Let's add balance to the wallet.
- Update our wallet balance to 20000 (or whatever you like)
- Check the wallet balance again to make sure it is updated
Orders
- Place a few market orders
- List all the orders
- Check the balance in the wallet if it is deducted correctly.
Portfolio
- Get Portfolio
- Check Total Portfolio Value
- Check Total profits
- Check Total investments

Note: The response data shown in this tutorial might differ from what you will receive as the market keeps changing. The price is not fixed. You will buy at a different price than mine

Token Generation

Every user needs to generate a separate token

To generate token, make the request as In userIdentifier, you can pass any user identifier like name, email, phone number, userId etc.

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/generateToken' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key",
    "userIdentifier": "any-user-identifier"
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json'
];
$body = '{
  "apiKey": "your-api-key",
  "userIdentifier": "any-user-identifier"
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/generateToken', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

You should expect the response like, copy the token, it will be used in all the requests below.

{
    "token": "some-token (Copy this token somewhere)"
}

Search Instruments

Let's search instruments For more details onn search instruments. Visit later Search Instrument

Let's to search for Reliance of exchange NSE

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/instruments/search' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
    "filterRequest": {
        "tradingsymbol": ["RELIANCE"],
        "exchange": ["NSE"]
    },
    "searchPatterns": {},
    "paginationDetails": {
        "offset": 0,
        "limit": 5
    }
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "filterRequest": {
    "tradingsymbol": ["RELIANCE"],
    "exchange": ["NSE"]
  },
  "searchPatterns": {},
  "paginationDetails": {
    "offset": 0,
    "limit": 5
  }
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/instruments/search', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response

Take a note of the instrument token here. We will place orders for Reliance later.

{
  "totalCount": 1, // Total count of matching results according to our filters
  "instruments": [
    {
      "instrument_token": 738561,
      "exchange_token": "2885",
      "tradingsymbol": "RELIANCE",
      "name": "RELIANCE INDUSTRIES",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.05",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "NSE",
      "exchange": "NSE"
    }
  ]
}

Now let's search by pattern "REL". It will find all the stocks that contains "REL" word. Experiment with it, ypu can increase the limit parameter to get more results. Limit defines how many top matching results you want.

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/instruments/search' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
    "filterRequest": {},
    "searchPatterns": {
        "tradingsymbol": "REL"
    },
    "paginationDetails": {
        "offset": 0,
        "limit": 5
    }
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "filterRequest": {},
  "searchPatterns": {
      "tradingsymbol": "REL"
  },
  "paginationDetails": {
    "offset": 0,
    "limit": 5
  }
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/instruments/search', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response

Here total count represents the number of matching results of which we request only 5 above in request.

{
  "totalCount": 3748, // Total count of matching results according to our filters
  "instruments": [
    {
      "instrument_token": 128083204,
      "exchange_token": "500325",
      "tradingsymbol": "RELIANCE",
      "name": "RELIANCE INDUSTRIES",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.05",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "BSE",
      "exchange": "BSE"
    },
    {
      "instrument_token": 128099844,
      "exchange_token": "500390",
      "tradingsymbol": "RELINFRA",
      "name": "RELIANCE INFRASTRUCTURE",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.05",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "BSE",
      "exchange": "BSE"
    },
    {
      "instrument_token": 128809476,
      "exchange_token": "503162",
      "tradingsymbol": "RELCHEMQ",
      "name": "RELIANCE CHEMOTEX INDUSTRIES L",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.05",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "BSE",
      "exchange": "BSE"
    },
    {
      "instrument_token": 129111300,
      "exchange_token": "504341",
      "tradingsymbol": "RELTD",
      "name": "RAVINDRA ENERGY",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.05",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "BSE",
      "exchange": "BSE"
    },
    {
      "instrument_token": 130998276,
      "exchange_token": "511712",
      "tradingsymbol": "RELICTEC",
      "name": "RELIC TECHNOLOGIES",
      "last_price": "0",
      "expiry": "",
      "strike": "0",
      "tick_size": "0.01",
      "lot_size": "1",
      "instrument_type": "EQ",
      "segment": "BSE",
      "exchange": "BSE"
    }
  ]
}

Get Current Quote

Let's get the current quote (current market status) of Reliance. I assume you have noted the instrument_token for Reliance as was pointed above in search instrument. You can give any number of instrumentIds in the request.

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/quotes?instrumentIds=738561' \
--header 'accept: application/json' \
--header 'authorization: yourToken'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'accept' => 'application/json',
  'authorization' => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/quotes?instrumentIds=738561', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "quotes": {
        "738561": {
            "volumeTradedToday": 0.0,
            "lastTradedQuantity": 20.0,
            "lastTradedTime": "1970-01-21T07:21:50.399+05:30",
            "change": 0.0,
            "oi": 0.0,
            "sellQuantity": 0.0,
            "lastPrice": 1205.3,
            "buyQuantity": 0.0,
            "ohlc": {
                "open": 1224.0,
                "high": 1239.5,
                "low": 1201.5,
                "close": 1205.3
            },
            "instrumentToken": 738561,
            "timestamp": "1970-01-21T07:25:39.046+05:30",
            "averagePrice": 0.0,
            "oiDayHigh": 0.0,
            "oiDayLow": 0.0,
            "depth": {
                "buy": [
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    }
                ],
                "sell": [
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    },
                    {
                        "quantity": 0,
                        "price": 0.0,
                        "orders": null
                    }
                ]
            },
            "lowerCircuitLimit": 1084.8,
            "upperCircuitLimit": 1325.8
        }
    }
}

Wallet

Let's check the wallet balance

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/wallet' \
--header 'authorization: yourToken'

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'authorization' => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/wallet', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "balance": 0.0
}

Let's add 10000 balance to the wallet

CURL
PHP

curl --location --request POST 'https://api.stockseyes.com/v1/public/wallet/addBalance' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000
}'

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "amount": 10000
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/wallet/addBalance', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "balance": 10000.0
}

Let's update the wallet balance to 20000

CURL
PHP

curl --location --request PUT 'https://api.stockseyes.com/v1/public/wallet' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
    "balance": 20000
}'

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "balance": 20000
}';
$request = new Request('PUT', 'https://api.stockseyes.com/v1/public/wallet', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "balance": 20000.0
}

Let's check the wallet balance again

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/wallet' \
--header 'authorization: yourToken'

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'authorization' => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/wallet', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "balance": 20000
}

Orders

Let's place a few market orders

Feel free to experiment with any instrument token you can find using search instruments
Place a market order to buy 1 Reliance share at the current market price

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/order/market' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
  "instrumentId": "738561",
  "quantity": 1
}'

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "instrumentId": "738561",
  "quantity": 1
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/order/market', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
  "order": {
    "id": "XIpgbHcoOIUoRFuZSGlB",
    "tradingSymbol": "RELIANCE",
    "instrumentId": "738561",
    "price": 1205.3,
    "quantity": 1,
    "status": "EXECUTED",
    "placedAt": "2024-12-23T07:50:32.926+05:30",
    "executedAt": "2024-12-23T07:50:32.926+05:30"
  }
}

Let's search for one another stock i.e. Bajaj Finance

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/instruments/search' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
    "filterRequest": {
        "tradingsymbol": ["BAJAJFINSV"],
        "exchange": ["NSE"]
    },
    "searchPatterns": {},
    "paginationDetails": {
        "offset": 0,
        "limit": 5
    }
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "filterRequest": {
    "tradingsymbol": ["BAJAJFINSV"],
    "exchange": ["NSE"]
  },
  "searchPatterns": {},
  "paginationDetails": {
    "offset": 0,
    "limit": 5
  }
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/instruments/search', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "totalCount": 1,
    "instruments": [
        {
            "instrument_token": 4268801,
            "exchange_token": "16675",
            "tradingsymbol": "BAJAJFINSV",
            "name": "BAJAJ FINSERV",
            "last_price": "0",
            "expiry": "",
            "strike": "0",
            "tick_size": "0.05",
            "lot_size": "1",
            "instrument_type": "EQ",
            "segment": "NSE",
            "exchange": "NSE"
        }
    ]
}

Place a market order to buy 2 Bajaj Finance share at the current market price

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/order/market' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
  "instrumentId": "4268801",
  "quantity": 2
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "instrumentId": "4268801",
  "quantity": 2
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/order/market', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
  "order": {
    "id": "g6oa0GqdMvajdlI9p6D5",
    "tradingSymbol": "BAJAJFINSV",
    "instrumentId": "4268801",
    "price": 1569.65,
    "quantity": 2,
    "status": "EXECUTED",
    "placedAt": "2024-12-23T07:52:24.807+05:30",
    "executedAt": "2024-12-23T07:52:24.807+05:30"
  }
}

Let's place a market order to buy 5 more Reliance shares at the current market price

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/order/market' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
  "instrumentId": "738561",
  "quantity": 5
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "instrumentId": "738561",
  "quantity": 5
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/order/market', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
  "order": {
    "id": "rbv6EcRzpWeQaKNqdS8v",
    "instrumentId": "738561",
    "tradingSymbol": "RELIANCE",
    "price": 1205.3,
    "quantity": 5,
    "status": "EXECUTED",
    "placedAt": "2024-12-23T07:53:29.573+05:30",
    "executedAt": "2024-12-23T07:53:29.573+05:30"
  }
}

Let's list all the orders

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/orders?limit=10&sortBy=placedAt&sortOrder=ASCENDING&offset=0' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/orders?limit=10&sortBy=placedAt&sortOrder=ASCENDING&offset=0', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "orders": [
        {
            "instrumentId": "738561",
            "tradingSymbol": "RELIANCE",
            "quantity": 1,
            "status": "EXECUTED",
            "id": "XIpgbHcoOIUoRFuZSGlB",
            "price": 1205.3,
            "placedAt": "2024-12-23T07:50:32.926+05:30",
            "executedAt": "2024-12-23T07:50:32.926+05:30"
        },
        {
            "instrumentId": "4268801",
            "tradingSymbol": "BAJAJFINSV",
            "quantity": 2,
            "status": "EXECUTED",
            "id": "g6oa0GqdMvajdlI9p6D5",
            "price": 1569.65,
            "placedAt": "2024-12-23T07:52:24.807+05:30",
            "executedAt": "2024-12-23T07:52:24.807+05:30"
        },
        {
            "instrumentId": "738561",
            "tradingSymbol": "RELIANCE",
            "quantity": 5,
            "status": "EXECUTED",
            "id": "rbv6EcRzpWeQaKNqdS8v",
            "price": 1205.3,
            "placedAt": "2024-12-23T07:53:29.573+05:30",
            "executedAt": "2024-12-23T07:53:29.573+05:30"
        }
    ]
}

Let's check the balance in the wallet if it is deducted correctly

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/wallet' \
--header 'authorization: yourToken'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'authorization => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/wallet', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "balance": 9648 // Remaining balance after buying all the shares
}

Portfolio

Let's get Portfolio

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/portfolio' \
--header 'authorization: yourToken'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'authorization => 'yourToken'
];
$request = new Request('GET', 'https://api.stockseyes.com/v1/public/portfolio', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
    "totalProfits": 0.0,
    "totalCurrentValue": 10371.10,
    "totalInvestedValue": 10371.10,
    "positions": [
        {
            "tradingSymbol": "RELIANCE",
            "instrumentId": "738561",
            "quantity": 6,
            "averageInvestedPrice": 1205.3,
            "currentPrice": 1205.3,
            "investedValue": 7231.80,
            "currentValue": 7231.80,
            "profits": 0.0
        },
        {
            "tradingSymbol": "BAJAJFINSV",
            "instrumentId": "4268801",
            "quantity": 2,
            "averageInvestedPrice": 1569.65,
            "currentPrice": 1569.65,
            "investedValue": 3139.3,
            "currentValue": 3139.3,
            "profits": 0.0
        }
    ]
}

Let's sell 3 shares of Reliance

Note: The quantity is negative here which signifies sell

CURL
PHP

curl --location 'https://api.stockseyes.com/v1/public/order/market' \
--header 'authorization: yourToken' \
--header 'Content-Type: application/json' \
--data '{
  "instrumentId": "738561",
  "quantity": -1
}'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'yourToken'
];
$body = '{
  "instrumentId": "738561",
  "quantity": -1
}';
$request = new Request('POST', 'https://api.stockseyes.com/v1/public/order/market', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
echo "\n"
?>

Expected Response:

{
  "order": {
    "id": "L09csp42ctQoYZAyausW",
    "tradingSymbol": "RELIANCE",
    "instrumentId": "738561",
    "price": 1205.3,
    "quantity": -1,
    "status": "EXECUTED",
    "placedAt": "2024-12-23T08:54:50.652+05:30",
    "executedAt": "2024-12-23T08:54:50.652+05:30"
  }
}

Exercise:

Check the wallet balance after selling 3 shares of Reliance from above, it should have increased.
List all the orders and check if it is showing the recent sell order.
Check the portfolio now, the quantity of Reliance should have decreased by 3.

Token Generation​

Search Instruments​

Get Current Quote​

Wallet​

Orders​

Portfolio​

Exercise:​

Token Generation

Search Instruments

Get Current Quote

Wallet

Orders

Portfolio

Exercise: